Inside Macintosh: AppleScript Language Guide / Part 2 - AppleScript Language Reference

Chapter 8 - Handlers / Command Handlers for Script Applications

Handlers for Stay-Open Script Applications

Idle Handlers

If a stay-open script application includes an Idle handler, AppleScript sends the script application periodic Idle commands whenever it's not responding to incoming events. The statements in the handler run periodically (every 30 seconds, by default).

For example, this handler causes a stay-open script application to beep every 30 seconds after it has been launched:

on idle
   beep
end idle

To change the rate, return the number of seconds to wait as the result of the script. For example, this script beeps every 5 seconds:

on idle
   beep
   return 5
end idle

If an Idle handler returns a positive number, that number becomes the rate (in seconds) at which the handler is called. If the handler returns a non-numeric value, the rate is not changed.

Remember that the result returned from a handler is just the result of the last statement, even if it doesn't include the word return explicitly. For example, this handler only gets called every 15 minutes.:

on idle
   set x to 30
   beep
   set x to x * x --the result (900) is returned from 
                  --the handler
end idle

To make sure you're not changing the idle rate, return 0 at the end of
the handler.